Updated information

This article has become partially obsolete, for now just see the documentation at wiki.merbivore.com

Bundle vs. Freeze

Our last release – 0.9.6 – already introduced the new bundle behaviour, set to replace what was formerly known as the freezer. The main goal of this concept is to bundle your dependencies with the application, making it independent of your system’s RubyGems. This makes your app portable, easy to deploy and it can be kept under source control more efficiently. With the upcoming 0.9.7 release, we were able to simplify the process, thanks to the introduction of merb.thor: Thor tasks for Merb.

The tasks come pre-installed with freshly generated apps, but are also available from merbivore.com/merb.thor for existing apps. Your existing app should run off a Merb >= 0.9.7 codebase, and you might need to regenerate your app’s Rakefile (run merb-gen app . and pick the Rakefile, be careful if you have custom tasks in there though).

You can use curl or wget to copy it to your local app or use the following to install it system-wide:

  thor install http://merbivore.com/merb.thor

However, using a merb.thor file local to your app is regarded as a best practice. Note that you can bootstrap a complete Merb stack, just by having the Thor gem installed and the merb.thor tasks available somewhere on your system.

Introduction

One of the main concepts behind the tasks is that they are context-aware, meaning that most of them adapt themselves to how (and where) they are run: in the context of an application, they will operate locally, or outside any application they target the system in general.

The existence of a local subdirectory called gems will indicate that operations are to be local, possibly within a Merb app. For new applications the ./gems directory will be generated by default, but for existing apps you can either add it manually or even better, use the following task to get started:

thor merb:tasks:setup

This will not only create the ./gems directory, but will install Thor, Rake and Rspec into it, so that the application is setup correctly for executing any further tasks. To keep your merb.thor file up-to-date you can run merb:tasks:update.

When installing certain known components, like the gems stated above, you’ll notice that some special executable wrappers are generated into the application’s local ./bin directory.

These executables will pickup any dependencies from the local ./gems dir, effectively running from the bundled gems, instead of relying on the system’s rubygems – they will get precedence over them, but can fall back to the system if needed.

This is especially important for the merb command, which should always be run as the local variant bin/merb for any app that is setup to run with bundled gems. Due to the specific load order and rubygems executable wrappers, it’s impossible to load merb-core from local gems, just by running the regular merb command. So this is how it’s done instead:

bin/merb

The same is true for bin/merb-gen and bin/spec to name a few.

Step-by-step: how to bundle a stable Merb stack from RubyGems

Run the commands below to setup and run an application to use official gem release versions of merb-core, merb-more and a Rack adapter of your choice (optional): mongrel, emongrel, thin and ebb are currently supported. You can always install your own gems later using merb:gems:install.

From within your application:

$ thor merb:tasks:setup 
$ bin/thor merb:stable -a mongrel
$ bin/merb

Step-by-step: how to bundle an edge Merb stack from Github

The following commands will setup a ./src directory and proceed to clone thor, extlib, rack, merb-core and merb-more from their official Github repositories. By specifying the—install option (needed for source installs) the gems are packaged and installed.

From within your application:

$ thor merb:tasks:setup 
$ bin/thor merb:edge --install
$ bin/thor merb:gems:install mongrel
$ bin/merb

Step-by-step: how to keep up with Merb on your system

To keep up with Merb’s development, you can track from git HEAD. First you need to either have merb.thor installed globally:

$ thor install http://merbivore.com/merb.thor

Or locally, using curl to fetch it into your directory of choice, for example:

$ curl -L http://merbivore.com/merb.thor > merb.thor

Finally, once you have it setup, any time you want to update your system’s gems you can just run the next command from that directory:

$ sudo thor merb:edge --install

Just like a regular ‘gem install’, it is usually preceded by sudo to be able to install it directly on your system. Note that we shouldn’t have a local ./gems directory, and didn’t use thor merb:tasks:setup in our directory.

Using your own forks or git repo’s with commit access

With all of the merb:sources and merb:edge tasks you can specify a yaml file using the—sources option. Alternatively, if you have a file called ~/.merb/git-sources.yml in your home directory, it will be picked up from there. The structure of the file is just a regular yaml hash:

merb-core: git://github.com/my-repo/merb-core.git
merb-more: git://github.com/my-repo/merb-more.git
awesome: git//github.com/my-repo/awesome.git

The entries you define here are merged with the defaults, so you don’t have specify them all, plus you can add some non-standard gems and their sources. You can then refer to them by their yaml entry key: thor merb:source:clone awesome

Signing off

The three scenarios outlined above should be enough to get you started, though there are some other useful tasks remaining. I’ll introduce some of them briefly, and you’ll find more information in the inline comments in merb.thor itself. Don’t forget to run thor -T ...

# retrieve the source of a known gem from github
thor merb:source:clone dm-core

# same as above, but looking up git urls from sources.yml
# merb-core: git://github.com/fabien/merb-core.git
thor merb:source:update merb-core --sources ./path/to/sources.yml

# refresh all gem sources in ./src
thor merb:source:refresh

# install what has been retrieved by merb:source:clone or merb:source:update
thor merb:source:install dm-core
thor merb:source:merb:install merb-core

# for meta-gems it's sometimes easier to install specific parts
thor merb:source:install merb-more/merb-slices

# some gems feature compiled C extensions - these need to be recompiled on your
# target deployment platform (use Capistrano, God...)
thor merb:gems:redeploy